
### this file contains all features/ideas that are/where meant to be implemeted

### this file is meant to store already well though out ideas and show big picture

### do not confuze this WISHLIST file with actual documentation

~~~
dotfilebackup docs


###### OVERVIEW ######

app for creating backups using .backup config files

- put .backup file in chosen dir and it's contents will be copied
- put exclude section in .backup and add regex patters to it to exclude
  files with matching name, path or full path from being copied
- put include section in .backup and add regex patters to it to make sure
  files with matching name, path or full path are copied even if excluded  
- run dotfilebackup command higher in dir tree
- wait for program to do it's job

unless set otherwise .backup files always inherit some properties
starting with first .backup file in user home dir even if command
is run from lower place in dir tree

by default every file not match by excludes will be copied

###### MODES ######

LAZY (--to)
    - new dir or archive file (add --archive) will be created
    - all relevant file will be copied

    backup will be created in passed path, no need to type name
    all missing parent dirs in passed path will be created automatically

    default name for dir

        backup_{username}_{hostname}_{datetime}

    default name for archive

        backup_{username}_{hostname}_{datetime}.{appropriate_sufix}

    to custimize this property set

        env    :  DOTFILEBACKUP_LAZY_MODE_NAME
        .backup:  lazy_mode_name

NEW BACKUP (--new)
    - new dir will be created
    - all relevant file will be copied

    all missing parent dirs in passed path will be created automatically

UPDATE BACKUP (--update)
    - existing dir will be used
    - only files that changed will be copied

    last modification timestamp is used to detected if file has changed
    check is performed if file name and backup dir relative path match
    - if file is older it will not be copied to backup dir
    - if file is newer it will overwrite one existing in backup dir

    # possibly in the future checksum could be used for that purpose as well

    cannot be used alongside --archive


###### INHERITANCE ######

/
├── .backup
├── home
*   ├── .backup
    ├── John
    ├── Jack <--------------- user Jack home inheritance barrier
    *   ├── .backup.conf <--- conf file valid only in user home dir
        ├── .backup <-------- first .backup for Jack user
        ├── Documents           
        *   ├── .backup
            ├── important
            *   ├── .backup
                ├── dotfilebackup_docs.md
                *

command run by Jack from /home/Jack/
command run by Jack from /home/Jack/Documents/important  # IMPORTANT


/.backup.conf
     |
     └────────┐ inherits settings            # "┐" 251x0 char from
              |                              # www.doc.ic.ac.uk/~svb/chars.html
/.backup      |
     X        |
     X        |
     X        |
/home/.backup |
     X        |
     X        |
     X        V
/home/Jack/.backup
     |
     | inherits some properties
     V
/home/Jack/Documents/.backup
     |
     | inherits some properties
     V
/home/Jack/Documents/important/.backup

command run by Jack from /                   # assuming Jack has
command run by Jack from /home  # IMPORTANT  # right permissions

/.backup.conf
     |
     | inherits settings
     V
/.backup
     |
     | inherits some properties
     V
/home/.backup
     |
     | inherits some properties
     V
/home/Jack/.backup
     |
     | inherits some properties
     V
/home/Jack/Documents/.backup
     |
     | inherits some properties
     V
/home/Jack/Documents/important/.backup

inheritance behavior can be changed by passing using flags and .backup setting



###### INTERPOLATIONS ######

interpolation like "{keyword-name}" can be used in certain places in cli and .backup

cli example:

    [jack@machine ~]$ dotfilebackup ... --new .../backups my_backup_{date}

.backup example:

    '''
    set_date_format: {day}-{month}-{year}
    '''

there are two ways to customize dotfilebackup cli interpolation

    set env variable use --ignore-env to ignore set values

    by being lazy, dotfilebackup will look for all parent .backup files
    and apply their inheritance automatically according to passed source

        dotfilebackup <source> ...

        use --renounce  # inheritance to give up on inheritance


###### INTERPOLATION KEYWORDS ######

# all date and time variable are taken the moment backup command is run

{day}            - current day number (01-31)
{day_name}       - current day name (monday - sunday)
{day_short}      - current day short name (mon - sun)
{weekday}        - current weekday number (1-7)
{month}          - current month number (01-12)
{month_name}     - current month name (january - december)
{month_short}    - current month short name (jan - dec)
{year}           - current year number (like 2024)
{year_short}     - current year number (like 24)
{date}           - current date, format defined in set_date
{datetime}       - current datetime format defined in set_datetime
{time}           - current time, format defined in set_time
{hour}           - current hour (00 - 24)
{min}            - current minutes (00 - 60)
{sec}            - current seconds (00 - 60)
{timestamp}      - current timestamp, different for linux and windows

{hash} or {h}    - only way to use hash, since it is used for comments

{username}       - username of user running command
{hostname}       - hastname of user running command

# only .backup files #

{self_path}      - relative path from first .backup file to dir containing
                   current .backup file this setting
                   IS     AFFECTED by --runaway  # from home         # IMPORTANT
                   DIFFERENT VALUE for each .backup file
{self_name}      - name of dir containing current .backup file
                   can be altered using set_dir_name setting         # IMPORTANT
                   DIFFERENT VALUE FOR EACH .backup FILE
{destination}    - absolute path to /.../target/--name dir


###### SETTINGS in .backup ######

lazy_mode_name: backup-jack-{date}                     # non inheritable setting

set_date_format: {day}-{month}-{year}                  #     inheritable setting
set_time_format: {hour}-{min}-{sec}                    #     inheritable setting
set_datetime_format: {date}_{time}                     #     inheritable setting

disinherit                    # excludes and includes  # non inheritable setting
disinherit_excludes                                    # non inheritable setting
disinherit_includes                                    # non inheritable setting

exclude                                                #     inheritable setting
include                                                #     inheritable setting


###### SETTINGS in .backup.conf ######

the same format and options as .backup file
this file is treated as configuration file only
and settings of exclude and include will be ignored

IMPORTANT THIS FILE IS ONLY VALID LOCATION IS USER HOME DIR


###### ENV VARIABLES ######

DOTFILEBACKUP_TIME_FORMAT
DOTFILEBACKUP_DATE_FORMAT
DOTFILEBACKUP_DATETIME_FORMAT
DOTFILEBACKUP_LAZY_MODE_NAME


###### LOGGING ######

by default backup log will be written to

    {backup_root_dir_name}.log

to customize where to create log file use

    --log-to <path>

log file name cannot be changed


###### USAGE ######

dotfilebackup --help
dotfilebackup --version

dotfilebackup --ls   [path]
dotfilebackup --info [path]

dotfilebackup <source> -to     <path>        [options]
dotfilebackup <source> -update <path>        [options]
dotfilebackup <source> -new    <path> <name> [options]


###### FLAGS ######

--help

    print help and exit

--version

    print current version and exit

--ls [path] [options]

    prints name/name of file/files along excluded/included indicators

    if no path is passed current dir is assumed

     *  - included by default      
     ~  - excluded by default     # place holder, just in case
    [i] - included by includes     
    [x] - excluded by excludes     

    sub flags:
    -a        print files starting with . without '.' and '..'
    -e        print only excluded files
    -i        print only included files
    -l        print one file per line

--lsd [path] [depth] [options]

    shows what you want to see, check it out XD

    depth is expected to be integer >= 0 or "all"
    default value is 'all'

    if no path is passed current dir is assumed

--check <path>

    if dir is passed print summary of settings/options for passed dir

    if .backup file is passed print if .backup is correct/valid

    if file is passed print

    if no path is passed current dir is assumed

--ignore-env

    if used all env variables starting with DOTFILEBACKUP will be ignored

--renounce  # inheritance

    if used no dotfilebackup will not attempt to look for parent .backup configs

--runaway  # from home

    if used .backup files will inherit some properties from .backup files
    beyond home dir, this setting is useful only if command is run from
    inside user's home dir

--log-to <path>

    path to dir to create log file in, log file name cannnot be changed and is

        {backup_root_dir_name}.log

--to <path>  # LAZY MODE

    new backup_root_dir_name will be created in passed path named

        backup_{username}_{hostname}_{datetime}

    if used alongside --archive flag

        backup_{username}_{hostname}_{datetime}.{appropriate_suffix}

    achieve will be created instead

--new <path> <name>

    PATH MUST NOT EXIST, backup dir or file if --archive flag is used
    is created with {path}/{name} path, interpolation keywords can be used

    following characters are disallowed in name:
    '`', '~', '#', '!', '$', '%', '^', '&',
    '*', '+', '=', '?', ':', ';', '|', '"',  # "'" is allowed
    '(', ')', '[', ']', '{', '}', '<', '>',
    ' ', '\n', '\r', '..',

--update <path>

    PATH MUST EXIST, path to existing backup dir
    interpolation keywords CAN NOT be used,

--archive [type_name]

    instead of creating dir in --new and copying files there create
    archive with name of {backup_root_dir_name}.{appropriate_suffix}
    optional type_name sets archive type

      available: zlib | gzip | bz2 | zipfile | tarfile
      default is tarfile for unix and zipfile for windows

~~~



















# normally if dir contains .backup file it will be copied, use this setting
# to tell program to ignore that and treat this as settings only file resulting
# in ALL INHERITABLE settings being inherited and but files being not copied
#
# default value is false
#
only_settings                                          # non inheritable setting



├── .backup
│   └──

[jack@machine ~]$ tree /




existing location like .../my/backup/location and pass --name backup-{date}
withch will allow program to access .../my/backup/location and crete dir like
"backup-10-11-2025" to hold your backup



# changes name of dir containing this .backup file
# useful when there is a need to keep all versions
# of single dir when using in place backup mode
#
# setting alters {self_name} for all other options      # IMPORTANT
# {rand_num} and {uuid} can not be used here            # IMPORTANT
#
# functionality is works because of .backup.info
# data file that is created inside backup's root dir
# if info file is deleted feature may not work correctly
#
# default value is {self_name}
#
set_dir_name = {self_name}-{date}         # non inheritable setting



    following characters are disallowed:
    '`', '~', '!', '$', '%', '^', '&', '*',
    '\\', '|', '/', '"', '<', '>', '?', '..',
    '\n', '\r', ' ',
















--log-name <name>

    name to use for log file, if file exists it will be overwritten
    default value is {backup_root_dir_name}.log

additional features
- cli auto compleate








{rand_num}       - generates random number with length of 32
{rand_num:X}     - generates random number and trims it to length of x
                   {rand_num:10} -----------> 1234567890
                   {rand_num} --------------> 12345678901234567890123456789012
                   {rand_num}{rand_num:1} --> 123456789012345678901234567890123
{uuid}           - generates random uuid with standard length of 32
{uuid:X}         - generates random uuid and trims it to length of x
                   {uuid:10} ---------------> a1b2c3d4d5
                   {uuid} ------------------> a1b2c3d4d5a1b2c3d4d5a1b2c3d4d5a1
                   {uuid}{uuid:3} ----------> a1b2c3d4d5a1b2c3d4d5a1b2c3d4d5a1q4g


           [jack@machine ~]$ dotfilebackup --ls
           [x] Desktop     *  Music         [x] Public  
            *  Documents  [i] my-notes.txt  [x] Templates    
           [x] Downloads   *  Pictures       *  Videos













#
